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Meet the Team, Meet the Workflow 



Meet the Team 


- small team: 12 people* 

- big task: maintenance of ~15000 A4 PDF pages* 

- content that is published at suse.com/doc and release notes 

- HTML, PDF, EPUB 

- we do not maintain man pages or --help 


* caveats 


Meet the Workflow 


- DocBook (ASCIIDoc?) 

- “Be conservative in what you do, be liberal in what you 
accept from others" 

- single-sourcing 

- multiple output documents 

- multiple output formats 

- Git + GitHub + Git Flow model + PRs + reviews 

- OBS builds documentation RPM packages 

- necessitates open-source toolchain 


DAPS 


- upstream DocBooktoolchain has functionality 
gaps 

- DAPS solves publishing toolchain issue for us 

- and maybe for you too? 

- pieces from various upstreams, "glued" together 

- upstream code: Java, C, XSLT, Python 

- glue code: Bash, Make, XSLT 

- command-line tool, editor-agnostic 


External Processes 


- translation 

- final publication 



Documentation: Client-Based Checks 



Validation 


- why? DocBook is XML 

- own Relax NG schema GeekoDoc (based 
DocBook 5.1) 

- "daps validate" 

- based on jing 

































Style Check 

- SUSE Style Guide-based 

- why? avoid confusion, cost 

- language rules + "soft" syntax rules 

- language: "in order to" > "to" 

- syntax: avoid lonely sections 

- needs XML integration, hence custom 

- Python, XSLT, regular expressions 





Style Check (II) 


- future plans 

- spell check 

- source lines 

- output formats 




Documentation: Server-Based Checks 



Travis 


- integrates with GitHub 
-free like beer 
-why? 

- we do not expect everyone to check their PRs (themselves) 
-quick feedback 

- consistently checks all output documents 

- Docker container with openSUSE and DAPS 

- validation + image check 



Travis (II) 


- future plans 

- publish to GitHub pages 

- integrate style checker (?) 



"docserv": Internal Publishing 


-why? 

-early (developer) feedback 

-valid XML does not in all cases mean valid PDF 
(unfortunately) 

-serverthat builds documentation 
- automatically once a day 
-on-demand from Web Ul 



-sends mail on breakage 
-document search 

- cron + PHP + Python + XSLT + ElasticSearch + web stuff 









Stylesheet Checks 




"dapscompare": Checking Stylesheets 

- custom DocBook XSL-based stylesheets 

- why? 

- XSLT is complicated (in its very own way) 

- DocBook 4 and DocBook 5 compatibility 

- many output formats to check 

- check whether bug fixes work 

- bonus: example documents for manual tests! 




















"dapscompare": Checking Stylesheets (II) 


- heavy-handed "competitors" 

- Python runner for DAPS, qtwebkit, 
Imagemagick 

- run before commit, run after commit 

- Python-QT GUI for comparing 






"dapscompare": Checking Stylesheets (III) 


- future plans 

- more example documents 

- run on Travis 




Links, Sources 


- (most) SUSE documentation repos: https://github.com/SUSE/?q=doc- 

- DAPS: http://opensuse.github.io/daps/ 

- Stylesheets: http://github.com/openSUSE/suse-xsl/ 

- Style Guide: https://github.com/SUSE/doc-styleguide 

- Style Checker: http://github.com/openSUSE/suse-doc-style-checker 


- Images from Unsplash (under the Unsplash License): https://unsplash.com/photos/UBhpOIHnazM (Ajeet Mestry), 
https://unsplash.com/photos/lstXvxHGoA4 (35mm), https://unsplash.com/photos/L9VXW4A9QZM (Charlotte Coneybeer), 
https://unsplash.com/photos/5-WslPUwhll (Cia Gould), https://unsplash.com/photos/3sl9_ubYlno (Daniel Hjalmarsson), 
https://unsplash.com/photos/UHMOIOd6iBU (Daniel von Appen), https://unsplash.com/photos/2XrFBLiTzKo (Evan Smogor), 
https://unsplash.com/photos/L94dWXNKwrY (Jesse Orrico), https://unsplash.com/photos/aWBPk_GBaCk (Koushik C), 
https://unsplash.com/photos/0tfz7ZoXaWc (Matt Briney), https://unsplash.com/photos/7oh6dJVhurM (Maxim Melnikov), 
https://unsplash.com/photos/TuAZPj1uaZs (Sam Poullain), https://unsplash.com/photos/CQI3Y5bV6FA (Scott Walsh), 
https://unsplash.com/photos/UHMOIOd6iBU (Yung Chang) 



We adapt. You succeed. 



